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1 INTRODUCTION 


1.1 Object 


This document describes how to use D’Fusion @Home to massively deploy augmented reality applications on PCs 
and Macs. 


This document is a technical reference manual and targets an audience with a technical background and involved 
directly within the D’Fusion @Home project creation and utilization. 


This document is a counterpart for the existing D’Fusion documentation and does not replace them. It provides 
information specific to massive deployment of D’Fusion @Home projects. 


1.2 External documentation 


1.2.1 Reference documents 
[01] D’Fusion Studio - User Guide, Total Immersion 
DFusion Studio - User Guide.pdf 


[02] D’Fusion Augmented Reality - Reference Manual, Total Immersion 
DFusion AR - Reference Manual.pdf 


[03] D’Fusion Augmented Reality - Lua API, Total Immersion 
DFusion AR - Lua API.pdf 


[04] D’Fusion Augmented Reality - Physics Plugin, Total Immersion 
DFusion AR - Physics Plugin.pdf 


[05] D’Fusion Computer Vision - Reference Manual, Total Immersion 
DFusion CV - Reference Manual.pdf 


[06] D’Fusion Exporter for Maya - User Manual, Total Immersion 
DFusion Exporter for Maya - User Guide.pdf 


[07] D’Fusion Exporter for Maya - Modeling Constraints, Total Immersion 
DFusion Exporter for Maya - Modeling Constraints.pdf 


[08] D’Fusion Exporter for 3dsMax - User manual, Total Immersion 
DFusion Exporter for 3dsMax - User Guide.pdf 


[09] D’Fusion Exporter for 3dsMax - Modeling Constraints, Total Immersion 
DFusion Exporter for 3dsMax - Modeling Constraints.pdf 


1.2.2 Other documents 


[10] LUA 5.1 Reference Manual 
www.lua.org/manual/5.1 
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1.3 Glossary & Acronyms 


TI Total Immersion 
AR Augmented Reality 
MLT Marker less Tracking 
CV Computer Vision 


Software Key A Software Key is necessary to play a D’Fusion @Home application. A 
Software Key can be of two types: Test or Final. 


Test Software Key A Software Key used to deploy a D’Fusion @Home scenario in Test mode 
(with a watermark). This key is generated when exporting the AR scenario from D’ Fusion 
Studio, or when using the tiProtectorAR2 tool (available to Pro users only). 


Final Software Key A Software Key used to deploy a D’Fusion @Home scenario in Final mode 
(without watermark). This key is provided by Total Immersion to D’Fusion Studio Suite Pro 
users only. 


1.4 Presentation rules 


Presentation | Content 
XXXXXX File name 
Loon Script: code samples 
XXXXXXX Key word 
ta XXXXXXX | Reminder: main information of the chapter 
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2 D’FUSION @HOME PRODUCT DESCRIPTION 


D’Fusion @Home is a deployment product available with D’Fusion® Studio Suite. 


D’Fusion® Studio Suite also includes D’Fusion Studio, the software that will allow you to design and develop 
Augmented Reality scenarios and create the associated media. 


D'Fusion @Home will allow you to massively deploy augmented reality applications on a large range of computers 
(PCs and Macs), and to play the AR scenarios created with D’Fusion Studio. 


2.1 @Home Web and @Home Desktop 


There are two versions of D’Fusion @Home: 


e D’Fusion @Home Web - for web-based AR applications: the final user uses a web-browser to play the 
augmented reality application, connected to a web-page on a distant web-server. 


e D’Fusion @Home Desktop - for standalone AR applications: no web browser and no internet 
connection are required to play the augmented reality application. 


Each version contains all the libraries, plug-ins and players required for @Home Web and @Home Desktop 
deployment, respectively. 


Depending on the final deployment of your AR application you may be using one or the other. The workflow 
described below is valid for both versions. 


2.2 Deployment workflow 
The following steps describe the workflow for creating a D’Fusion @Home application: 


2.2.1 Create your AR scenario 


Use D’Fusion Studio to create your AR scenario. 


If you want to ensure the compatibility of your application across a large range of platforms (PCs and Mac), read 
the recommendations described in section 3 below. 


Documentation on how to use D’Fusion Studio to create AR scenarios is available in [01]. 


2.2.2 Export your project 


Export your D’Fusion Studio project using the “@Home” export target setting. 


This action creates a folder (the “exported project folder”) designed to contain all the files necessary to play your 
@Home application (AR scenario, media, etc.). Your exported project, exported media and so on are to be found 
inside this folder. 


Documentation on how to use D’Fusion Studio to export AR scenarios is available in [01]. 


Note: we recommend using encryption when exporting your project. 


2.2.3 Launch and test your application 


When your project is exported, a Test Software Key (.dfk file) is automatically generated and saved next to your 
exported project (i.e. in your exported project folder). This Test Software Key will allow you to play your AR 
application in Test mode with the suitable player: D’Fusion @Home Desktop Player if you are deploying for 
desktop platforms, or D’Fusion @Home Web Player if you are deploying for the web. 
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2.2.4 Final deployment 


Once your application is tested and validated, you can proceed to final deployment by requesting a Final Software 
Key from Total Immersion. 


If you are a D’Fusion Studio Suite Pro user, you can make this request by sending us your Test Software Key(s) 
(.dfk file(s)). Total Immersion will send the Final Software Key(s) (.dfk file(s)) back to you. 


The Final Software Key will allow you to play your augmented reality application in Final mode (without 
watermark). 


To play your application in Final mode, replace your Test Key(s) with your Final key(s) in your exported project 
folder(s). Then follow the steps described in chapter 0. 


Please note that deployment for commercial use (without a watermark) is only available with D’Fusion Studio 
Suite Pro. 
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2.3 Hardware and Software requirements 


2.3.1 System configuration 


Internet Explorer 


Chrome 


Firefox 


Windows 8 * 
32 & 64 


Windows Windows 
XP SP3 32 | Seven 32 & 64 


Minimum, Recommended: IE 9 (32 bits only) 
Maximum IE10 (32 bits only) (10.0.9200.x) 


Minimum: Chrome 16.0 
Maximum, Recommended : Chrome 23.0.1271 


Minimum: Firefox 15.0 (32 bits only) 
Maximum: Firefox 16.0.2 (32 bits only) 
Recommended: Firefox 16.0.2 (32 bits only) 


D’Fusion® @Home 


2012-12-14 
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Mac (Intel architecture) 


MacOS MacOS 
10.6 Snow 10.8 Mountain 
Leopard Lion 


MacOS 
10.7.5 Lion 


Minimum: 15.0 (32 bits mode) 
Maximum: Firefox 16.0.2 (32 bits mode) 
Recommended: Firefox 16.0.2 (32 bits mode) 


Minimum: Safari 5.1.7 ** 
Maximum: Safari 6.0.1 ** 
Recommended: 6.0.1** (wo keyboard input) 


Safari 


Minimum: Intel Dual Core (or core 2 duo) 1.5 GHz or AMD equivalent 
Recommended: Intel Dual Core (or core 2 duo) 2.4 GHz or AMD equivalent 


Minimum: 1 GB 
Recommended: 2 GB 


Minimum: Most graphics cards (Nvidia, ATI, Intel chipset, except Via chipset) 
Recommended: Powerful graphic card (Nvidia, ATI) with 256 MB memory 


Minimum : 100 MB for the software. More is needed for applications 
Camera Specifications depends on final usage 


(*) Windows 8 editions: Windows 8 Pro, Windows 8 Enterprise 


CPU 


Memory 


Graphic card 


Hard disk 


Figure 1: System requirements 


Remarks: 
Notebook PCs can be supported, but the scenario must be light (as opposed to complex). 


Windows operating systems with the “N” or “KN” tag (European and South Korean zones only) must be updated 
to be able to run Windows Media Player. 


We recommend having the latest Windows update installed. 
Mac based on Power PC processor are not supported! 


Ongoing maintenance for the D’Fusion @Home Web plugins on Mac OS X internet browsers is not planned for 
2013. In other words, Safari and Firefox on Mac OS X will remain compatible insofar as these browsers don't 
change their event model interface support implementation, and continue to support the Carbon interface. 


>] 26 Av. du Général Charles de Gaulle 92150 
SURESNES 

® +33 (0) 1 46 25 97 42 

& www.t-immersion.com 


TOTAL DFusion @Home - Deployment Guide.doc 


IMMERSION 


8 / 66 


D’Fusion® @Home 


TOTAL IMMERSION & 4 Deployment guide eUterseelt 


2.4 Cross-platform features availability 


The following tables describe D’Fusion features’ availability through various platforms and products. All D’Fusion 
supported targets have been given for comparison purposes. 


D’Fusion Pro is set as a reference. As a result, if a feature is available for D’Fusion Pro, it will appear in the table 
even if it is not available or only partially available for another platform or product. 


Cross platforms features matrix @Home @Home Mobile Mobile for Adobe 
Reference : D'Fusion Pro Windows MacOSX Android iPhone Flash Player 


2D Overlay 
2D Text 
Particles 
Script Engine Lua 


Video based features 
Video texturation from file 
Video recording (with sound) 
Screen capture 
Image processing 

Web manager 

Inputs 


Mouse 
Keyboard 
GPS 


Accelerometer 

Multi-touch 

Compass 
Plugin SDK 


3D Engine (Ogre 3D) 
Physic Engine (Bullet) 
Component architecture 
Barcode plugi 


(*) partial Web Manager for Flash : many things available directly within Flash 
(**) details on supported barcode formats are to be found in D'Fusion AR2 documentation 


Figure 2: Cross-platform rendering features 
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Cross platforms features matrix @Home @Home Mobile Mobile for Adobe 
Reference : D'Fusion Pro Windows’ MacOSX Android iPhone Flash Player 
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Figure 3: Cross-platform Computer Vision features 
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3 PROJECT CREATION 


This section describes how to ensure the compatibility of your AR applications across a large range of computers 
(PCs and Macs) when creating your scenarios with D’Fusion Studio. This way, your final application will most likely 
work properly on the final user’s computer, even with low configurations. 


For information on how to create AR scenarios, please refer to the relevant documentation [01]. 


3.1 Project recommendations 


3.1.1 Video Capture and Rendering window 


Video Capture Size vs. Rendering Window Size: 


| Standalone | Web 


320*240 640*480 320*240 640*480 
800*600 1024*768 640*480 800*600 


Camera selection: 


The camera selection functionality is executed only if there are 2 or more cameras recognized as connected to the 
computer. If there is only one camera recognized, the one-recognized camera is automatically used. Note that 
even if the user has only one physical web-camera connected, there can be other video input devices recognized 
(graphical card video input, video acquisition card, virtual cameras, etc.). 


To allow the final user to choose the proper camera, the selection camera mode must be enabled from D’Fusion 
Studio: in the properties of your video capture (“Object Editor” window), check the “Select dialog” option. 


You can also open the camera configuration .xml file and add the word “selection” in the parameter: 


<VIDEO_CAPTURE_FRIENDLY_NAME>selection</VIDEO_CAPTURE_FRIENDL Y_NAME> | 


With the camera selection option enabled, the application will show a dialog box. The dialog box will have the 
same look as the OS of the final computer (OS-specific). In a web based project, the dialog box can be 
customized. More informations is provided in section “5.1.9 Camera selection in detail”. 


Select camera 


Hercules Dualpix Exchange 
eprey-210 Video Device 1 Built-in iSight 
Peripherique video USB 
Decklink Video Capture 
uEye Capture Device 1 


Cancel | 


Figure 4: Windows camera selection Figure 5: MacOSX camera selection 
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3.1.2 Video Capture and Distortion Correction (DEDISTORTION) 


The camera used by the final user is usually unknown when developing the application for large scale 
deployment. It is thus recommended to deactivate the distortion correction process from the video capture. 


To deactivate this option, use the following parameters when configuring the camera calibration in D’Fusion 
Studio: 


Video Dedistortion 


videocapture_live 


Camera \Calibration 


Internal Parameters 
Max 
Focal 


Optical Center 


Tangential 


Figure 6: Camera Calibration settings 


The camera “Max (x,y)” must be the chosen resolution and the “Optical Center (x,y)” must be half of these 
values. 


You can also deactivate the distortion correction process by setting the DEDISTORTION parameter to false in the 
camera calibration .xml file: 


<DEDISTORTION>false</DEDISTORTION> | 


3.1.3 Tracking 


Here are our recommendations: 
e 2 objects tracked at the same time maximum 


e 1 planar object with 20 autoinit keyframes maximum (choose one detection by frame for the autoinit 
mode) 


e 300 interest points maximum 
e For 3D tracking you need to use “.obj” files. 


The tracking initialization phase can be very long. This phase is proportional to the number of tracked objects. To 
avoid an extended amount of time, it is recommended to split the tracking part of the scenario by making one 


tracking configuration file for each tracked target, and loading the tracking configuration file when the user has 
chosen the object to track. 


Note that the tracking scenario must be configured in “Classic” mode in D’Fusion Studio “Computer Vision” panel. 
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3.2 Media recommendations 


3.2.1 Rendering generalities 


The D’Fusion @Home players are designed to use the platform default renderer. 
The OpenGLES 2 renderer is not supportd by the D’Fusion @Home players. 


3.2.2 Cross-platform projects 


To distinguish media or parameters specific to Windows from media or parameters specific to Mac OS X, you can 
check the “Alternative platform” option of the media’s properties (in D’Fusion Studio’s “Object Editor” window), 
then choose an alternative media for each platform. 


3.2.3 Short names for files and paths 


The length of file names (character number) must be limited. Some operating systems do not support too long 
names. 


Similarly, the path name must not be too long (so the folder number must also be limited). 

Example: 
File names like Object_3d_that_have_an_excessivly_long_name.mesh are strictly forbidden! 
Path like scenario/media/folder_1/folder_2/folder_3 are strictly forbidden! 


3.2.4 Anti-aliasing 


Anti-aliasing can be activated from the D’Fusion Studio “Project Settings” window. 


It is recommended to use a value of 4 for the anti-aliasing (or an even number power of two). If the anti-aliasing 


value is not supported by the graphics card, the software will automatically decrease the value until a supported 
value is found. 


3.2.5 Lights 


It has been noted that all 3D objects were blank on some computers. The issue is that some graphic cards do not 
handle lights with zero constant attenuation. 


The solution to this problem is to avoid using O for the “constant” parameter of the light properties (D’Fusion 
Studio “Object Editor” window). 
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3.2.6 Textures 
Format: 


Uncompressed file formats (such as TGA and BMP) are to be avoided, since they are too heavy and will take a 
long time to download. JPG and PNG formats should be preferred: 


e JPG for natural images 


e PNG if transparency is needed or if a large part of plain color is used, PNG format is preferred to JPG 
because it has a better compression quality 


Size: 


Downscale the textures. This will decrease the loading time and allow the application to run on lower grade 
computers without graphic cards (like Intel chipset). 


We recommend using less than 512*512 pixels size. For example, for a D’Fusion @Home window of 800*600 
pixels, if the 3D object takes only 50% of the window, a 256*256 pixels texture is enough. 


For materials and textures that do not use mip-maping (mip-map is set to 0), the texture sizes must be power of 
2. It means width and height must have one of these values (2, 4, 8, 16, 32, 64, 128, 256, 512, etc.) 


By using an adequate texture resolution, you will gain: 
e Good visual quality, the texture display well in the final rendering 
e Less GPU memory, then a faster rendering 


e Smaller file size, which means a faster downloading time 


3.2.7 Meshes 


Please, read the relevant documentation [06 & 07] and [08 & 09]. 
Size: 


We recommend having less than 100.000 polygons displayed on the screen at the same time. Each individual 
mesh file must have less than 63.000 polygons. The number of polygons affects the amount of time it takes to 


download an application. Reducing the number of polygons in a scene is a good way to keep the download time 
lower. 


Re-use shared part: 


Many 3d meshes have identical meshes or sub meshes, but have different textures. We recommended using one 
mesh for multiple 3d object instances. This will decrease downloading time and improve 3d rendering. 


D’Fusion Exporter for Maya: “Public” mode is the only mode supported on all office PC with Intel graphic 
board, even if they are powerful. 


3.2.8 Sound 


We recommend using the “.ogg” format because the sound size will be smaller and it will be compatible both 
with Windows and MacOsx. 


“Mono” channel sounds are preferred; dual channel double the sound file size. 


For sounds that must be recorded during video recording, they must be Mono, 16 bits, 44100 Hz and the 
parameter “streaming” must be set to “true”. 
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3.2.9 Video 


We recommend either embedding the video with your application or embedding the video with one of the 
downloaded data folders used by your application. Please read the size recommendations below. 


You can also play a video hosted on another server by providing the address to the video. In such case, the video 
is read in the distant server and played in your application, which can result in less smoothness than with 
standard streaming. Constraints with this method include: 


e The address must be static, a dynamic link will not work 
e The video can't be encrypted, or otherwise it won't be read 
e If the connection to the server is lost, the reading will not pick up where stopped 


In both cases, please check that the format is compatible with D’Fusion, as explained below. 


Size: 
e Avoid excessively long video; video less than 1 minute is preferred. 
e Choose the size according to the D’Fusion window: 640*480 or 320*240. 


e Keep in mind that the video size will directly impact downloading time. 


Format: 


e Recommendations according to the OS: 
e Windows - Format: .avi, Codec: MJPEG or Format: .wmv, Codec: WMV9 


e MacOsX ~- Format: .mov, Codec: Mpeg4 
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3.3 Effects recommendations 


3.3.1 Particles 


Please note that some parameters are not available on Mac Os X. List of supported parameters: 
e Emitter Type 'Point' 
e Emitter Type 'Box' 
e Emitter Type 'Ellipsoid' 
e Emitter Type 'Cylinder' 
e Emitter Type 'Ring' 
e Emitter Type 'HollowEllipsoid' 
e Affector Type 'LinearForce' 
e Affector Type 'ColourFader' 
e = Affector Type 'ColourFader2' 
e =Affector Type 'ColourImage' 
e Affector Type 'ColourInterpolator' 
e =©Affector Type 'Scaler’ 
e Affector Type 'Rotator' 
e §©Affector Type 'DirectionRandomiser' 


e Affector Type 'DeflectorPlane' 


3.3.2 Shadows 


Shadows can be added to the 3D scene. Although it impacts performance, shadows add a lot of realism to 3D 
rendering. To minimize the impact of shadows on rendering performances, follow these recommendations: 


e Shadows must be activated with only one light source. 
e The light source must be a spot light type, not a directional or point light type. 
e The maximum resolution for a shadow texture is 1024x1024. 512 is generally fine. 


e Shadows must be activated on moving objects only. For static objects, pre-calculated shadows must be 
used. 


3.3.3 Environment mapping 


If an environment mapping texture is applied on an object, the material must not have the argument 
“scene_blend alpha_blend” or shadow casting must be disabled on the object. Otherwise a crash is generated. 
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3.3.4 Shaders 


If a material uses a shader, a second rendering technique must be added to the material to handle non 
compatible graphic cards. If the backup rendering technique is not in the material, the material will be blank or 
you will have a crash. 


If the @Home application is being used on a large user platform, the CG language is preferred to other shading 
language. HLSL is for DirectX and will not work on Mac OS X platform. 


A list of existing profiles on graphic cards can be found at: http://developer.nvidia.com/object/cg_profiles.html 


More generally, the use of shaders is not recommended for @Home deployment. 


Moreover, please note that the D’Fusion tiShaders have not been designed and are not recommended for the 
D’Fusion @Home Deployment. For any further information on the DFusion tiShaders please refer to the document 
“DFusion tiShaders — User Guide”. 


To optimize the rendering, the “Default Renderer” rasterizer, a DFusion project setting, should be set. This will 
enable the use of openGL for macOSX, and directX3D for windows. 


3.4 Mouse use 


The following table describes the cross-platform mouse button availability for D'Fusion @Home Web applications. 
It will help you define the optimum use of the mouse in your @Home Web scenarios for large platform 
compatibility. 


@Home @Home | @Home 
MacOSX MacOSX MacOSX 


= 10.6 < 10.6 


| Safari Safari 


@Home 
Windows 


-@Home @Home 
Windows | Windows 


Internet Chrome Firefox 


Explorer 


| Firefox 


Left button + * + + + + + 
Right button +* + + + - - 
Wheel +* + + + - - 


Figure 7: Cross-platform mouse button Position and Click availability 


(*) Using Internet Explorer in Protected Mode (under Windows OS platform > XP like Vista, Seven ...), the input 
mouse is limited to 3 application reloads in the same web browser instance. No problem in using other web 
browsers or IE in non Protected Mode under Windows. 
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4 TEST AND PROJECT VALIDATION 


Once your project is ready, you may want to test it on several computers and in conditions similar to the final 
release (encryption settings, required files, packaging) before proceeding to final deployment. 


You can do your tests using the Test Software Key (.dfk file) that is automatically generated when your project is 
exported. 


This key will allow you to play-test your final AR application with the suitable player (D’Fusion @Home Desktop 
Player for @Home Desktop applications or D’Fusion @Home Web Player for @Home Web applications) and in 
final-like conditions. 


If you are a Pro user, you can also use the tiProtectorAR2 command line tool to generate compatible test keys (or 
full scenario processing). See section 6.5 for more information on how to use this tool. 


4.1 @Home Desktop applications 


You can test your @Home Desktop application using the D’Fusion @Home Desktop Player already installed in your 
computer. 


The D’Fusion @Home Desktop Player is installed with D’Fusion Studio. This player can be found in the D’Fusion 
Studio “Deployment” installation directory and it will allow you to test your @Home application on a Windows PC. 
@Home Desktop applications for Mac can be tested on Windows before proceeding to final deployment, described 
in section “5.2.2 Standalone packaging on MacOSX platform”. 


To launch the player and test your @Home Desktop application on your PC, use the following command line: 


%HomePlayerDirectory% |DFusionHomePlayer. exe —f 
YourExportedProjectDirectory| YourExportedProject.dpd 


In Test mode (i.e. a Test Software Key is associated with the exported scenario), the player displays a tattoo: 


LU Fusion: 


@Home Test Version, Free» Not For 


AUGMENTED BY Commercial Use 
TOTALJMMERSION 


Figure 8: @Home Desktop test version tattoo 
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4.2 @Home Web applications 


D’Fusion @Home Web applications can be tested online (using a web server) or locally (on a local computer). 


If your scenario has some interactions with a web page, it is recommended that you test your application with all 
the interactions and callbacks such as JavaScript functions. 


The following sections describe how to test your @Home Web application. 


4.2.1 Download D’Fusion @Home Web 


Here are the instructions to start using D’Fusion @Home Web: 


e¢ Download D’Fusion @Home Web from our website. This package contains the players for Windows and 
Mac OS X, the default JavaScript files, and the web browser plug-ins for @Home Web AR applications. 


e Extract the package in your project folder. 


Note: If you have more than one project requiring D’Fusion @Home Web, download the package and 
extract it once for each project in each project folder (see the folder structure below). 


e Once you have D’Fusion @Home Web on your computer, export your project with D’Fusion Studio. 
e Ideally, you should organize your projects with the following directory structure: 


+ MyProject - A folder containing a D’Fusion project 
+ DFusionProject - Project folder: contains all D’Fusion Studio 
project files (project.dpd, media, etc). 
+ ExportedProject - Exported project folder: contains all exported 
files (project.dpd, media, test keys, etc). 
+ DFusion@HomeWeb — Extracted D’Fusion @Home Web package 
+ local 
+ online 
+ tools 
+ AnotherProject - A folder containing another D’Fusion project 


Once your project is exported, you can start testing your @Home Web application. We advise you to test your 
application locally before proceeding to an online test. 


Note: the above directory structure will allow you to have your exported project folder next to your D’Fusion 
Studio project folder, with each targeted deployment platform readily visible. 


4.2.2 Local test 


To test your @Home Web application locally: 


e Copy the contents of your exported project folder into the “scenario_test” folder available in the 
“D’Fusion @Home Web” > “local” folder: 


+ DFusion@HomeWeb 
+ local 


+ scenario_test 


By default, "sceneario_test" contains the minimum files required to test your @Home Web application 


locally. 
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e Launch “sampleAR2_test.html” in a web browser. 


If your exported project is not named “project.dpd”, you will have to edit line 30 of 
“sampleAR2_Test.html” (“scenario_test/project.dpd”) for your application to launch properly. 
See also “4.2.4 HTML integration” below. 


4.2.3 Test web server 
Details on how to proceed to Final deployment are provided in section 5.1. Test deployment is similar, except that 
you don’t need to use the PrepareFolderForUpdate tool described in section 5.1.2. 
You can test your @Home Web application online using an online web server: 


e Prepare your exported project folder for download using the PrepareFolderForUpdate tool. This tool 
generates a package ready for download, including the file “.update.xml”, which lists all the files that 
must be downloaded. Refer to section “5.1.2 PrepareFolderForUpdate tool” for more information on how 
to use this tool. 


e Copy the contents of this folder into the “scenario_test” folder available in the “D’Fusion @Home Web” 
> “online” folder: 


+ DFusion@HomeWeb 
+ online 


+ scenario_test 


By default, "sceneario_test" contains the minimum files required to test your @Home Web application 
online. 


e¢ Configure your FTP tool so as to ensure that copying is done in binary mode and that hidden files are 
also downloaded. More information on FTP is available in section 5.1.4. 


e Upload the content of your “online” folder to your online web server. 
e Open a web browser and connect to “sampleAR2_Test.html” on your server. 


If your exported project is not named “project.dpd”, you will have to edit line 30 of 
“sampleAR2_Test.html” (“scenario_test/project.dpd”) for your application to launch properly. 
See also “4.2.4 HTML integration” below. 


Your D’Fusion @Home Web application can now be tested online. 


When your AR scenario has to dynamically download data from a web server, you will also need to generate Test 
Key(s) for the data to download: 


e Use the tiProtectorAR2 tool on the folder containing the data to download (and dynamically use). The 
tiProtectorTool will export this data, i.e. it will generate a Test Software Key for this data and encrypt it 
if necessary. Please, read chapter 6.5. 


e Prepare this folder as a package to download using the PrepareFolderForUpdate tool. Please refer to 
section “5.1.2 PrepareFolderForUpdate tool” for more information. Then, you can follow the steps 
described above. 
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4.2.4 HTML integration 


You should at least include the following code inside the HTML <body> tag of your test. htm/file: 


<body> 
<div id="InteractionCell’> </div> 
<div id="plugin_dfusion’> 
<script language="JavaScript’> 
var player = ""; 


If (tiMacOSXSupported()==false) { // Windows version 
Player = “DFusionWebPlayer/DFusionWebPlayer’, 
} else { 


Player = “DFusionWebPlayerMacOSX/DFusionWebPlayer 


tiGenerateDFusionWebHTML( 

"DFusionApplication”, // project specific identifier 

800, 600, // X and y 

Player, // test player to be used 

"my_scenario/project.dpd”, // exported scenario to be used 
"ChooseCamera’, // JS function invoked for HTML camera selection 
"PersonalizedAction’, // JS function invoked when the application is ready 
“true”, // camera selection mode: if true = selection is made via Web-Page 
"SplashCont/splash.ssc” // customized splash screen file 


ye 
</script> 
</div> 
</body> 


Make sure that the names and paths in the web page are correct. 


You will find information on Final web integration in section 5.1. Test web integration is similar, except that the 
augmented experience is tattooed. 
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On the web server, the most commonly used directory structure is: 


+ MyProject 


+ 


+ 


Note especially that there are hidden files named “.update.xm 


index.html 
other files 


js 


(test content folder) 
(main web page) 
(html, image, ...) 


—- some JavaScript files ... 


plug-in 


- D’Fusion navigator plug-in files 


DFusionWebPlayerTest 
+ resources 


- player resource files 


- .update.xml 
— DFusionWebPlayer.dll 
- splash.zip 


—- other 


dlls 


DFusionWebPlayerMacOSxX 

- .update.xml 

+ DFusionWebPlayer.bundle 
scenario 

—- .update.xml 

— project.dpd.dfk 

— project.dpd 


—- other 


files (3D, audio, video, 


automatic download functionality to work properly. 


4.3 Final validation 


(including default splash screen) 


configuration files) 


2012-12-14 


that must be present on the online server for the 


When deployment test is completed, you'll have to send your Test Software Key to Total Immersion, who will 
process the key according to your contract and generate a final deployment key called Final Software Key. 


The Final Software Key will then be sent back to you. This key is to be used in the exact same way as the test 
one: replace your test keys with your final ones in your application’s export folder and re-apply steps for 
scenario packaging (such as “PrepareFolderForUpdate” for web applications), then use it like in 
deployment test. 
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5 FINAL DEPLOYMENT 


5.1 Web integration 


5.1.1 D’Fusion @Home Web application structure 


There are 3 main parts that compose the D’Fusion @Home Web solution: 
e Plug-in — the application that allows integration into the browser 
e Player — the 3D engine 
e Scenario — the 3D media and scripting files needed for the AR experience 


The following figure illustrates the interconnection between these 3 parts and the supported web browsers: 


D’Fusion @Home Web 
Plugins 


PC: Internet 
Explorer 


Plugin IE (Activex) 


D’Fusion 
@Home Web 
Player 
version PC 


PC: Firefox 


Plugin FF PC Scenario 
(Version can be 
universal or OS 


specific) 


PC: Chrome 


PC: Safari 


Scenario 


| 
| 
i | 
Mac: Safari m HEISS2cehie | 
Leopard I | 
; Pa | | 
Plugin Mac DFusion 2 Pei eee | 
Mac: Firefox @Home Web 
Player 
version Mac 
Mac: Safari Plugin Safari Mac 
Snow Leopard 
Figure 9: D’Fusion @Home Web architecture 
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The exact usage of these components is: 


D’Fusion @Home Web Plug-in = project-independent, platform-specific and browser-specific 


An application that provides a “glue” to the web-browser executed by the final user 


It has its own installer: the installation is made in the same way as Adobe's Flash: It is an on-usage 
check. If the application is already installed the application will be installed automatically 


Web Plug-in has a form of ActiveX for Internet Explorer, Mozilla Plug-in for Firefox 
It allows to launch “Players” and handles the interface between the “Player” and the Web page itself 


The plug-in is generic for all our @Home Web products. So, the actual 3D computation is not contained 
in the plug-in, but in the “Player” 


D’Fusion @Home Web Player = project-independent, platform-specific 


3D engine of the application 

Binary package (compiled code) 

Binaries are specific to a given platform: Win/Mac. So there are 2 binaries (Win and Mac) 
Presented in the form of a .dll (Win) / bundle (Mac) collection 

For a given platform (either Win or Mac), it is browser-independent 

Allows the loading of one or more scenarios per project (see “Scenario” below) 


One player execution = one scenario is interpreted 


Scenario = 3D media and configuration = project-specific, either platform-specific or platform-independent 


A collection of configuration files, 3D medias, sounds and videos (if any) 


It can be platform-independent (i.e. the same configuration for Win/Mac) or platform-specific (if there is 
some media that is platform-specific, especially video = e.g. WMV for Win, MOV for Mac) 
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5.1.2 PrepareFolderForUpdate tool 


The PrepareFolderForUpdate tool is installed with D’Fusion Studio, in the folder installation directory > 
Deployment > Tools. 


This is a command line application that allows you to prepare the scenario data for download, for @Home Web 
projects. You can optionally compress the scenario project files in order to decrease the download time. 


The generated .update.xml indexes all the compressed data that must be downloaded. 


Command parameters are: 


| Option _ Name Description 


-i input folder name Set the folder where the program will browse to find media to 
download 

-O output folder name_ | Set the folder where the program will put data 

-C Compress option All files from input folder will be compressed before being copied to 
output folder 

-ie extension to ignore | concerned files won't be in the output folder 

-if folder to ignore concerned folders won't be in the output folder 

-iec extension to ignore | concerned files will be copied without compression 

for compression 


For the “ie”, “if” and “iec” options, a list can be provided with commas used for separations. 


For the input folder, keep in mind that a path with a space must be enclosed with quotes. 


Example: 


PrepareFolderForupdate.exe —i “scenario” —o “onlineScenario” —c —iec “zip,wmv,mp4,jpg,png” 
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5.1.3 Application download, initialization & execution 


For a user that has never used any of D’Fusion products: 


e First the plug-in needs to be installed. The plug-in presence / non-presence is checked automatically. If 
not present, the plug-in installer is downloaded and launched automatically. A special case for Firefox: 
Firefox needs to be closed during installation (please note this is a Firefox issue and that Adobe Flash 
Installer is doing the same.) 


e Once the plug-in is installed, the player is downloaded automatically 

e Once the player download is finished, the plug-in launches the player 

e The player downloads the scenario to be executed (one scenario at a time) 

e The player initializes the 3D scenario — i.e. possible creation of necessary data-structures 

e The player initiates camera selection form (via JavaScript) but only if there are two or more cameras 


e The player launches the 3D engine and ensures the JavaScript communication (input/output) 


Any future launch will be faster. If the player and/or media have not changed, then no additional data download 
is necessary and data-structures already created are reused: 


e The plug-in launches the player 
e The player initializes the 3D scenario 
e The player initiates camera selection form (via JavaScript) but only if there are two or more cameras 


e The player launches the 3D engine and ensures the JavaScript communication (input/output) 
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5.1.4 Web server directory structure 


The most common directory structure on the web-server for D’Fusion @Home Web applications is listed below: 


+ MyProject 
—- index.html (main web page) 
- other files (html, image, ...) 
+ Js 
— javascript_browser_sniffer.js 
—- totalimmersion_dfusion_web.js 
—- totalimmersion_dfusion_web_config.js 
— totalimmersion_dfusion_web_custom. js 
+ plugin 
— DFusionHomeWebPlugin.Installer.dmg 
— DFusionHomeWebPlugin.Installer.exe 
—- totalimmersion_dfusion_web_plugin.js 
—- totalimmersion_dfusion_web_pluginMac.js 
+ DFusionWebPlayer 
+ resources 
- player resource files (including default splash screen) 
- .update.xml 
DFusionWebPlayer.dll 
- splash.zip 
- other dlls 
+ DFusionWebPlayerMacOSxX 
- .update.xml 
+ DFusionWebPlayer.bundle 
+ scenario 
- .update.xml 
— project.dpd 
— project.dpd.dfk (final key delivered by TI) 
- other files (3D, audio, video, configuration files) 
+ scenario-Mac (optional) 
- .update.xml 
— project—Mac.dpd 
— project—-Mac.dpd.dfk (final key delivered by TI) 


other files (3D, audio, video, configuration files) 


Note: there are hidden files named “.update.xml” that must to be present on the server and are used for the 
automatic download functionality. 


Note: There are two versions of the D’Fusion @Home Web Plugin Installer for Windows, the 
“DFusionHomeWebPlugin. Installer.exe” and the “DFusionHomeWebPlugin.InstallerFull.exe”. The first version 
detects if the Package redistribuable Microsoft Visual C++ 2010 (x86) is already installed on the target computer 
and, if not, downloads it from the Microsoft web site and installs it. The second version integrates the Package 
redistribuable Microsoft Visual C++ 2010 (x86) so doesn’t download it if needed. By default, the javascript sample 
files given for web integration use the “non-full” version “DFusionHomeWebPlugin.Installer.exe”. 
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To prevent any future problems, be very careful when you are uploading your files onto your web server: 


All file transfers need to be binary, even if the file extension corresponds to a textual file. 


Thus, be sure that the way you are actually putting the files on the web server is correctly performing a binary 
transfer on all files. Typically, if you are using an FTP client, be sure your communication is correctly configured in 
a “Binary” mode, avoiding “ASCII” and “Automatic” (Filezilla example here): 


BINARY TRANSFER SETUP IN FTP CLIENTS 


& FileZilla 


File Edit View BUEWSISS) Server 


Bookmarks Help 


GE 7 Heal Process Queue CTRL+P 
Default file exists action... 
Host: 
fe 2: 
Preserve timestamps of transferred files CTRL+T ASCII 
® Binary 
Manual transfer... CTRL+M 


4 FileZilla File Edit View MagretnGs e 


Process Queue 
Default file exists action... 


Preserve timestamps of transferred files 


Manual transfer... 


Auto ima 
#T Asc = 


#M 


—_—_— 


Figure 10: Filezilla transfer mode 


Also, do not forget that there are hidden files to be transferred (those beginning by a dot “.”, especially the 
“,update.xml”.) To be able to see such files, be sure that your ftp client (or any other directory browser) is able to 
display such files (locally and remotely.) If not, you may encounter problems with FTP clients when trying to 
erase directories that seem to be empty but still contain the “.update.xml” file. 


FORCED SHOWING OF HIDDEN FILES IN FTP CLIENTS 


& FileZilla 


GE (EB | t+] Q) 


Host: 


File Edit Yiew Transfer [ES@729) Bookmarks Help 


¥ Force showing hidden files 


Cancel current operation 


Reconnect CTRL+R 
Disconnect CTRL+D 


LOfT 


¥ Force showing hidden files 


For instance, in the Filezilla FTP client, you need to have the option “Force showing hidden files” activated: 
Figure 11: Filezilla hidden files mode 


We do not recommend using Windows Explorer’s FTP capability for web server uploads and configurations as this 
specific client does not provide full configuration functionality (e.g. does not permit to show hidden files). 
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5.1.6 Required web server configuration for download 


The binary mode for download has to be ensured by the web server. This must be configured for all files, 
even if their extension corresponds to a textual file. 


Files have to be accessible for download. 


To prevent any future problems, please ensure that this is supported and funcional on your hosting 
web server. 


Note that these points are mandatory and if not ensured, the D’Fusion @Home Web application will 
not function at all, because either no files could be found on the server by the D’Fusion @Home Web 
application, or, if found, corrupted files may have been downloaded. 


If your server is managed by IIS, please refer to the section “Issues to be prevented with IIS” in 
section 8 Troubleshooting” 


5.1.7 HTML Integration 


The prerequisite for the HTML integration is the inclusion of the following standardized JavaScript files into the 
HTML’s <head> tag. The project specific JavaScript functions (PersonalizedActions here) are to be defined in the 
same place (the PersonalizedActions function here): 


<head> 
</-- some project specific HTML’s head data here --> 
<script src="./Plugin/totalimmersion_dfusion_web_plugin.js”> </script> 
<script src="./Plugin/totalimmersion_dfusion_web_pluginMac.js”> </script> 
<script src="./js/javascript_browser_sniffer.js”> </script> 
<script src="./js/totalimmersion_dfusion_web_contig.js”> </script> 
<script src="./js/totalimmersion_dfusion_web.js”> </script> 
<script src="./js/totalimmersion_dfusion_web_custom.js”></script> 
</head> 
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In a default, minimal way, the necessary code to be included into the HTML <body> tag is: 


<body> 
<div id="InteractionCell’> </div> 
<div id="plugin_dfusion’> 
<script language="JavaScript’> 
var player = ""; 
if (tiMacOSXSupported()==false) { // Windows version 
Player = “DFusionWebPlayer/DFusionWebPlayer’, 
} else {// MacOSX version 
Player = “DFusionWebPlayerMacOSxX /DFusionWebPlayer*; 


tiGenerateDFusionWebHTML( 

"DFusionApplication”, // project specific identifier 

800, 600, // X and y 

Player, // player to be used 

"my_scenario/project.dpd”, // scenario to be used 

"ChooseCamera’, // JS function invoked for HTML camera selection 
"ReadyToStart’, // JS function invoked when the application is ready 
‘true’, // camera selection mode: if true = selection is made via Web-Page 
"SplashCont/splash.ssc” // customized splash screen file (optional) 


x 
</script> 
</div> 

</body> 


Please note that the entire code mentioned above must be incorporated into the web page, especially the 
InteractionCell used for the default HTML camera selection functionality. In addition, please note that the 


focus function call is necessary for the application to function correctly when incorporated within an iFrame on 
Firefox-like browsers. 
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The inclusion of the application itself in the web-project is done within the HTML <body> tag by invoking the 
tiGenerateDFusionWebHTML function, called with project-specific parameters. This function takes 9 


parameters: 
1. 


Name of the plug-in object (DFusionApplication): this name will be used if you want to interact with 
the plug-in/player using JavaScript. 


Width of the window used by the plug-in. This value should be equal to the rendering dimensions 
declared by the project-specific scenario. 


Height of the window used by the plug-in. This value should be equal to the rendering dimensions 
declared by the project-specific scenario. 


Path to the absolute or relative path to the player file (dll under Windows and bundle under Mac 
OS X, but you can avoid the extension.) 


Path to the scenario: absolute or relative path to the configuration file 


Callback to select the camera (CameraOptions function in the listing below): function called if more 
the one capture device is present on the end user’s computer. The goal of this function is to display 
a list of devices and let the user choose the correct one. If you want a different behavior than the 
default, take the body of this function from the totalimmersion_dfusion_web_custom.js file, create 
a new function and modify the behavior to meet the exact project requirements. 


Callback is invoked when the player has finished initializing. (ReadyToStart function): function 
called when the player starts the rendering. It can be used to modify the web page when the 
player starts. For instance, to make a menu appear with HTML buttons/elements to control the 
@Home Web application via JavaScript. 


Camera selection Boolean switch: if true, the camera selection is made via Web-Page and JS 
mechanism, If false, the application’s internal dialog box (look is OS specific) will be used 


Path to a project-specific splash screen configuration. If not specified, a default version of the 
splash screen is used. 


This function generates an in-place HTML code containing the correct links to all the files required to run your 
@Home Web application (plug-in, player and scenario) stored on the distant side (web-server). This gives the 
final web integrator the possibility to keep the code of the main page minimal, while retaining the ease of future 
modification of one or several parameters. 
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5.1.8 Communication with the web page using JavaScript 


The D’Fusion @Home Web application has the capability of communicating with a web page using JavaScript: 
e output: capable to invoke a JavaScript function with or without arguments 
e input: it is possible to pass arguments from the JavaScript to the application 


A default communication protocol is provided ensuring a basic communication. If this is not sufficient, the default 
protocol can be modified and adjusted to meet the exact needs of the Web project. This is done by appending 
input/output invocations, enriching the basic communication protocol. 


5.1.8.1 Output to JavaScript 


The D’'Fusion @Home Web application is capable of invoking any prior known JS function via its name (also called 
JS call-backs) with or without arguments. In the case of JS, all arguments are strings. 


If the callback function does not exist in the actual loaded web-page document, the invocation is skipped and 
nothing happens. 


5.1.8.2 Input from JavaScript 


In the *.js files provided with the web application, you can find an “ExecuteCommand(command)” JavaScript 
function. This function binds directly the “command” argument to the web plug-in. This single argument has to be 
a string formatted in the following way: 


function_name 'argO'argl'arg2'... 


The function_name refers either to: 
e The pre-defined D’Fusion @Home Web command (not case sensitive): 
CAMSELECTED -— used for camera selection 


e Or, in any other case, the function is supposed to be project-specific and is dispatched to the applicable 
layer configurable by the scenario. 


Arguments can be omitted or present. If present, an argument’s definition is surrounded by quotation marks (in 


the beginning and at the end). If more than one argument is passed, the arguments must be separated by an 
extra set of quotation marks. 


Example of JS function that will invoke keypresses within the D’Fusion @Home Web application: 


function MakeKeystrokeActions()){ 
for (var | = 0; i < arguments.length; i++) { 


ExecuteCommand("PLAYWITHKEY "'+arguments{i]+’”"); 


PLAYWITHKEY is the name of a pre-defined D’Fusion @Home Web command that will ensure a SW keystroke. 
This function can be called as follows: 


MakeKeystrokeActions( “y”, “a”, “m” ); 
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This call will invoke the ExecuteCommand function three times and ensure 3 SW keystrokes in this way: 


ExecuteCommand("PLAYWITHKEY ‘y"); 


ExecuteCommand("PLAYWITHKEY a"); 


ExecuteCommand("PLAYWITHKEY ‘m"),; 
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5.1.8.3 Signaling error with JavaScript 


In the case of any irregular behavior in the D’Fusion @Home Web Plug-in / Player / Scenario execution, a specific 
JavaScript function is called during the experience so that the web-page can monitor the actual status. 


This function is defined in the file totalimmersion_dfusion_web_custom.js. Modify it so it feet your needs 


function DFUSION_EVENT_Error(status) 


//add your code to display information 


Most of these errors are used for internal debugging. The only error that will be useful on a final (release) version 
is the TI_LEETH_LOAD_VIDCAP_FAILED, received when the webcam can’t be used. 


1 TI_EETH_INIT_PLUGIN_FAILED Problem with plug-in initialization 

2 TI_LEETH_DL_SPLASH_FAILED Problem with splash screen download 

3 TI_LEETH_LOAD_SPLASH_FAILED Problem when charging splash screen 

4 TI_EETH_DL_PLAYER_FAILED Problem with player download 

5 TI_LEETH_LOAD_PLAYER_FAILED Problem when charging player 

6 TI_EETH_INIT_PLAYER_FAILED Problem with the player initialization 

7 TI_EETH_PLAYER_FAILED Problem with the player execution 

8 TILEETH_DL_SCENARIO_FAILED Problem with scenario download 

9 TILEETH_LOAD_SCENARIO_FAILED Problem when charging scenario 

10 TI_LEETH_LOAD_VIDCAP_FAILED No webcam available or the webcam is already used or not properly installed 
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5.1.9 Camera selection in detail 


An HTML camera selection mode is supported and provides enhanced “web-page” integration. 


In this case, the D’Fusion Web application is communicates with the JS and it is the HTML that ensures the visual 


representation of the camera selection dialog box. Once selected, the JS passes the chosen camera to the 
D’Fusion Web application. 


The actual mode is chosen via the tiGenerateDFusionWebHTML function argument, as described previously in this 
document. 


The HTML-based camera selection is done via JS calls and via a web-page element that provides selection 
functionality (ComboBox). The actual sequencing is as follows: 


e D’Fusion @Home Web Player executes a JS function and passes a list of cameras that were actually 
recognized on the PC. The name and contents of this JS function are configurable and can be 
completely project-specific, as already mentioned above. The camera-selection function name is passed 
to the player when generating the HTML via the tiGenerateDFusionWebHTML; note the 
“SelectCamera_function” argument and the camera selection switch that is on “true”: 


tiGenerateDFusionWebHTML( 
"DFusionApplication 
800, 600, 
"DFusionWebPlayer/DFusionWebPlayer” 
"“my_scenario_pc/project.dpd’, 
"“SelectCamera_function’, // JS function invoked for HTML camera selection 
"ReadyToStart’, 
‘true’, // camera selection mode: if true = selection is made via Web-Page 
"“SplashCont/splash.ssc”// customized splash screen file 


e Web page JS function creates a selection dialog. 


When selecting a camera, the D’Fusion @Home Web Player execution is interrupted. The application is 
will wait until the user selects a camera. 


e User chooses a camera. Web page JS intercepts that the user has finished the selection. 


e Actual selection has to be signaled by the JS to the D’Fusion @Home Web Player via the following (note 
the CamSelected standardized command and note that the camname has to be one of cameras 
identifiers that the D’Fusion @Home Web Player has passed to the JS in the cameras list): 


ExecuteCommand('"CamSelected "'+camname+“"); | 


This mechanism is really flexible. D’Fusion @Home Web does not force in any specific way how the camera 
selection is to be made. It can be a Flash application that handles all that camera selection choices. 


From the D’'Fusion @Home Web application point of view there is only: 


e An output via JS function transmitting to the web-page with a list of cameras 


e A waiting loop -will wait until the web page executes and input JS function with “CamSelected” 


command + camera name as an argument. 


The typical (default) JS code for the camera selection is to be found in the following file: 
\js\totalimmersion_dfusion_web_custom.js 
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The function, once invoked, is injecting an HTML code containing a ComboBox with the camera list and a button 
so that the user can validate the selection into the following div: 


<div id="InteractionCell’> </div> 


This div has to exist within the document (as was mentioned previously), otherwise, the HTML page will not 
display any camera selection and the D’Fusion @Home Web application will be blocked in an infinite waiting loop 
for the user’s selection that never arrives (so, in a dead-lock). 


function ChooseCamera() 

ie 
var SelectFormHtml = ""; 
SelectFormHtml += "<FORM name=|“ChooseCamera|”>";; 
SelectFormHtm! +=" <SELECT NAME=|"CAMERAS|”>"; 
SelectFormHtm! +=" </SELECT>"; 
SelectFormHtml +=" <input type=button value=|"Camera selected|“onclick=" 
SelectFormHtml += "CamSelected(this.form.CAMERAS. options” 
SelectFormHtm! += ‘[this.form.CAMERAS.selectedindex]. value)>"; 
SelectFormHtm! += "</FORM>"; 


document. getElementByld(‘InteractionCell”).innerHTML = SelectFormHtml; 
for (var | = 0; i < arguments.length; i++) 


document. forms{‘ChooseCamera']. CAMERAS. options{i] = new 
Option(arguments/ij,arguments/i]); 
A 
y 


function CamSelected(camname) 


t 


document. getElementById(‘‘InteractionCel!”).innerHTML = ""; 
ExecuteCommand("CamSelected "'+camnamet+”")- 


Note that this is only the default behavior and the application integrator can entirely change the contents of this 
function, replacing it by a project-specific one. In such a case the “InteractionCell” existence or name is entirely 
dependent on the project specific web-page construction. 
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5.1.10 JavaScript customization 


In the file totalimmersion_dfusion_web_custom.js, you can find a set of function you can customize to 
meet your needs. 


In the 


tiDFusionWebNotSupported: This function is called by tiGenerateDFusionWebHTML() if the 
system is not supported. Use this function to display an error message to the end user. The name of 
this function must not be changed. 


tiDFusionWebCanFindExecuteCommand: This function is called by ExecuteCommand() if the 
function cannot be called on the plug-in. Use this function to display an error message to the end user. 
The name of this function must not be changed. 


tiInstallationRequieredForGecko: This function is called by tiGenerateDFusionWebHTML() if the 
plug-in need to be (re)installed. This function is not used under Internet Explorer but by all other 
browser (Firefox ...). Uses this function to display information to the end user so it call download the 
plug-in setup. The name of this function must not be changed. 


tiDFusionPluginNeedToBeUpdated: This function is only called under Mozilla Firefox MacOSX. Our 
plug-in version detection does not work correctly on this configuration. So the version is checked while 
the plug-in is running. The plug-in ask the web page which version is required. If the plug-in version is 
older, it stops and_ calls this’ function (defined by g_NeedToUpdateFunc in 
totalimmersion_dfusion_web.js). Then you are responsible to do something (change the webpage, 
remove the plug-in by updated the content of the current web page ...) and then inform the end user it 
will need to update the plug-in (like what is done in tiInstallationRequieredForGecko()). If you 
change the name of this function update the value of g_NeedToUpdateFunc in 
totalimmersion_dfusion_web.js. 


ChooseCamera: Function called by the plug-in when a camera selection is required. The name of this 
function is passed to the plug-in through tiGenerateDFusionWebHTML().This function receive an 
array of string as unique parameter. Each string is a camera name. To select a camera look at the 
CamSelected function. 


ReadyToStart: Function called by the plug-in when the scenario is starting. The name of this function 
is passed to the plug-in through tiGenerateDFusionWebHTML(). This function does not receive any 
parameter. 


file totalimmersion_dfusion_web_plugin.js, you can find a set of global vars to meet you special 


preferences: 


e g_tiInstallerName: this variable references the DFusion @Home Web plugin installer to use. By default, 


the version is DFusionHomeWebPlugIn. Installer.exe. This is the non full version that doesn’t include 
the Package redistribuable Microsoft Visual C++ 2010 (x86), and downloads it (and installs it) only if 
necessary. You can choose at your convenience to use the 
DFusionHomeWebPlugIn. InstallerFull.exe instead. 
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5.2 Standalone version packaging 


5.2.1 Standalone packaging on Windows platform 


5.2.1.1 Installer and license agreement 
Many installer packages are available to create the installation setup. 
We recommend NSIS. 
When creating the installer, the license must be included. Third-party licenses must also be included. 


if) D'Fusion @Home Desktop 3.20.18794 Setup: License ... | =) 


TOTALIMMERSION & ’'@ DFusion® @Home Desktop Player 


1 Please review the license agreement before installing D'Fusion @Home 
Desktop 3.20.18794. If you accept all terms of the agreement, select the first 
option below. Click Next to continue. 


DEVELOPMENT LICENSE AGREEMENT FOR TOTALIMMERSION *« 


D'Fusion Studio SOFTWARE INCLUDING: 
- D'Fusion Studio Commercial License 
- D'Fusion Studio Educational License (EDU) 


| accept the terms of the License Agreement 
® | do not accept the terms of the License Agreement 


Cancel | | 


Figure 12: D’Fusion @Home Desktop License Agreement 


& It is mandatory to present the License Agreement to the final user. Third-party licenses must also be 
included. 


5.2.1.2 Installer and Package redistribuable Microsoft Visual C++ 2010 


The D’Fusion @Home Player needs the Package redistribuable Microsoft Visual C++ 2010 (x86), called “vcredist”. 
The “vcredist_x86.exe” installer required version has been copied in the D’Fusion CDRom, in the subfolder called 
“redist”. 


Source to download the required vcredist is on the official Microsoft download center: 


http://www.microsoft.com/downloads/fr-fr/confirmation.aspx?FamilyID=a7b7a05e-6de6-4d3a-a423- 
37bf0912db84 


{& Please ensure your D’Fusion @Home desktop application installer detects if the installation of the 
Microsoft Visual vcredist 2010 is required, and install it if needed. 


A way to do so could be to call the DFusionHomeDesktopPlayerSetup.exe installer, provided in the DFusion 
CDRom: this will install the DFusion Home Desktop Player and manage the vcredist installation. 
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5.2.1.3 Install directory and shortcut 


The final D'Fusion @Home Desktop application can be launched in two ways. If the final scenario is placed near 
the executable, it can be directly executed. If the final scenario is placed in a folder different from the application 
folder, then the player must be launched in command line mode or by a shortcut and the scenario file path must 
be specified by using the -f argument. 


Most often, the installation directory has the following structure: 


S® MY_APPLICATION (je \&) 


Fichier Edition Affichage Fayoris utils ? a 


Adresse |((D C:\Program Files\{MY_CUSTOMER\MY_APPLICATION | EJ ox 
Nom Taile Type 

(player Dossier de Fichiers 

(resources Dossier de Fichiers 

(yscenarios Dossier de fichiers 

[PS |My_APPLICATION, bat 1Ko Fichier de command... 

au uninstall,exe 113Ko Application 


< 


Figure 13: D’Fusion @Home Desktop Install Directory 
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5.2.2 Standalone packaging on MacOSX platform 


5.2.2.1 Placing the final scenario in the Contents Application folder 


With Mac OS X operating system, applications may include in the application bundle all the resources, libraries 
and frameworks that are needed. It is, consequently, recommended to put the exported scenario folder with the 
content final software key into the DFusion@HomePlayer bundle. 


The scenario folder content has to be placed into the “Scenario” folder, into the application bundle. To do this, 
you open the DFusion@HomePlayer package content. 


Name Date Modified 
Open 
Show Package Contents 
Move to Trash 
Get Info 
Compress “DFusionHomePlayer” 
Duplicate 
Make Alias 


Quick Look “DFusionHomePlayer” 
Copy "DFusionHomePlayer” 


Label: 
x BGease 


More > 


Figure 14: Show MacOSX package contents command 


When the package content is opened, the exported scenario folder content with final software key must be placed 
in a “Scenario” folder, placed in the “Contents” folder. 


fl “Scenario” folder name is mandatory. The DFusion@HomePlayer loads the first file with the “dpd” 


extension in “Scenario” folder as the scenario to play. 


DFusionHomePlayer 


DEVICES Name 
LJ Contents 
Info.plist 
PLACES PkgInfo 
{) Frameworks 
{@j Macos 
(J) Resources 
{@ Scenario 
project.dpd 
project.dpd.dfk 
video.xml 
{3 RenderingData 
LQ ScriptLUA 
(@ TrackingData 


SHARED 


SEARCH FOR 


12 items, 133,8 GB available 


Figure 15: Copy Scenario in Contents folder 
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5.2.2.2 Changing the icon 


The application icon can be customized. You can change it by replacing the DFusion@Home icon in the 
Contents/Resources folder with your own icon. If you change the icon name, you must also update the Info.plist 
with the correct icon name. 


5.2.2.3 Package the application 


Apple provides an application named PackageMaker with its developer utilities. There are other ways to create 
installation packages, but we recommend using PackageMaker. 


{& It is mandatory to present the License Agreement to the final user. 


PackageMaker allow the easy creation of an installer for Mac OS X and to add a “read me” and “License” step. 


\v| Install_ Package - Interface Editor - en 


Software License Agreement 
License Panel 


© Background , ' 


. APPENDIX 1 / None 
© Introduction \\ Embedded 


e Fil 
Read Me % TOTAL IMMERSION © File: 
@ licanse \ D'FUSION RUNTIME se/UcenseUk.rtf) @- 
END USER LICENSE AGREEMENT 


Different localizations cannot 
mix embedded and file-based 
resources for the same panel 


© Finish Up 

You should read carcfully all the terms and conditions of this License agreement 
; (hereinafter referred to as the “Agreement”) between TOTAL IMMERSION and 
yourself (hereinafter referred to aa “You” or “"LICENSEE™) 


By completing the installation process and using the Software’chocking the option 
‘l accept the terms in the License Agreement”, you agree to be bound by all the 
terms of the Agreement 

If You do not agree to be bound by the terms of the Agreement, then do not install 


and/or use the Software 


1, DEFINITIONS 


Go Back Continue 


Figure 16: License agreement on Mac OS X 


The relocation option must be unchecked; it will be more convenient and will secure reinstallation if the 
application is already installed. 


(teste wie 


DF usionHomePiayer pe 
ost Package: DFusionHomePlayer 


Contents 


Configuration Contents Components Scripts 


v¥ © DFusionHomePiayer 


& Component Allow Relocation Allow Downgrade 
>» @ OF usionHomePiayer.app al 


Figure 17: Mac OS X installer - relocation 


This document does not explain how to use PackageMaker, please refer to the PackageMaker User Guide. 


When the installation package is created, we recommend using Disk Utility to create a disk image (.dmg file) from 
the installation package. Disk image ensure that binary integrity is preserved and is automatically mounted after 
being downloaded. Therefore, it simplifies the installation process for the final user. 
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6 ADVANCED 


6.1 Splash Screen customization 


In D'Fusion @Home, the splash screen is easily and highly customizable. It is composed of an .xml description file 
and some resources (image files). You will be able to play image sequences, define you own text areas, choose 
your background image, etc. 


To launch your own splash screen (in testing versions), you have to use the -ssc command argument. 
Example: 


Your splash (ssc file + images) is contained in the “MyOwnSplash” folder which is at the same level as the 
scenario folder (“MyScenario”) and at the same level as the D’Fusion @Home testing application folder 
(“Dfusion@HomePlayerTest"). To launch your scenario with your own splash screen in this application, you have 
to enter the command: 


> DFusionDesktopPlayer.exe -ssc “..\MyOwnSplash\splash.ssc” -f “..\MyScenario\project.dpd” 

or 

> “@Home\DFusionDesktopPlayer.exe” -ssc “MyOwnSplash\splash.ssc” -f “MyScenario\project.dpd” 
It depends of your current directory. 


6.1.1 SSC file 


The SSC file is an xml file that aims at describing the splash screen according to the downloading/loading scenario 
evolution. In some sections of the xml you will recognize this logic. 


The main section of the file is “splash” with no attribute. It is just a starting point for the splash loader. In this 
section you have to declare at least three sub sections: 


e window: it describes the splash screen window style 
e progressbar: it describes the progress bar look and behavior through the different steps 


e step: with its sub-sections it describes the splash screen behavior (images sequences, background 
image, text areas, etc.) 


6.1.2 Window section 


“Attribute Description 
width the width in pixel of the splash window 
height its height in pixel 
transparency can be “true” or “false”. It controls the WS_EX_TRANSPARENT style of the 


window. If this value is set to “true”, the flag is active and the 
backgroundcolor parameter is ignored 


show can be “true” or “false”. Controls the visibility of the splash screen 


backgroundcolor a string containing RGB values of the background color of the window. Note 
that if a background image covers the entire splash window, the background 
color never appear 


Example: 
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<window width=640 
height=480 


transparency="false” 
show="true” 
backgroundcolor="105, 140, 189’/> 


6.1.3 Step 


In a step section, the user will describe the splash screen behavior during the scenario loading or in the scenario 


downloading (in the web case) with text and image sequences. 


With the standalone player, you can only define one step section (sections declared afterwards will be ignored). 
With the web version, you can have two step sections: one corresponding to the downloading step, the other one 


corresponding to the scenario loading. This is not mandatory. 


In each step you can define your own customized dynamic content like the progress bar, image and text 


sequences. The following sections describe how to configure it. 


6.1.4 Progress bar 


“Attribute "Description | 

Xx indicates, in pixels, the x (horizontal) coordinate of the upper-left corner of 
the progress bar relative to the upper-left corner of the splash window 

y same as x, for the vertical coordinate 

width the width in pixels of the progress bar 

height its height in pixels 

backgroundcolor string containing RGB values of the background color of the progress bar 

showbackground can be “true” or “false”. If the “false” value is set, the background rectangle 
(not the status bar) will be transparent 

show can be “true” or “false” 

color a string containing RGB values of the progress bar 

evol_param can be “time” or “progress” It describes how the progress bar will evolve. The 
“progress” value is available on both steps and the percentage progression is 
the percentage downloaded or an arbitrary loading percentage status. 

loop Only active if evol_param="“time” indicates if the progress bar loops. 

duration Only active if evol_param="“time” indicates the sequence duration in seconds 

Example: 


<progressbar x=228 y=193 width=325 height=10 background='"255,255,255” showbackground='true” 


show="true” color="7,224,250'/> 
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6.1.5 Image sequence 


Attribute "Description | 
ID a string that corresponds to the name you want give to the sequence 
evol_param can be “time” or “progress” It describes how the sequence will evolve. The 


“progress” value is only available in a “downloading” step and the percentage 
progression is the percentage downloaded. This attribute has an impact on 
the evolutionstep attribute (in an image section) interpretation 


loop only active if evol_param="“time” indicates if the sequence loops 

Duration only active if evol_param="time” indicates the sequence duration in seconds 
Example: 

<image_sequence ID="foreground” 


evol_param="time” 
loop="true” 
duration=2> 


</image_sequence> 


These attributes describe some global parameters of the sequence. The different image sub-sections help us to 
describe precise behavior of this sequence. An image sub-section describes one image, its size, its location, etc. 


| Attribute Description 


location indicates the image path, relative to the ssc file 

Xx indicates, in pixels, the x (horizontal) coordinate of the upper-left corner of 
the displayed image relative to the upper-left corner of the splash window 

y same of x, for the vertical coordinate 

scalex note that we cannot control the width or height coordinates, because they 


are automatically calculated. However, you can adjust the rendered image 
size with scale (x or y parameters) 


scaley same of x, for the vertical coordinate 
show can be “true” or “false” 
evolutionstep a number that indicates when the splash screen has to pass to this <image>. 


If, in image_sequence section, the evol_param attibute is set to “progress”, 
the evolutionstep attribute must be contained between 0 and 1 and 
corresponds to a percentage. If evol_param="“time”, then O< evolutionstep 
value < image_sequence's duration attribute value and corresponds to a time 


in seconds 
color a string containing RGB values of the text 
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Example: A complete image_sequence description can look like this: 


<image_sequence ID="foreground” 
evol_param="time” 
loop="true” 
duration=0.5> 
<image location="fireball001L jpg” x=100 y=0 
scalex=0,4 scaley=1 show="true” 
evolutionstep=0.0 /> 


<image location="fireball002 jpg " evolutionstep=0.1 /> 
<image location="fireball003. jpg " evolutionstep=0.2 /> 
<image location="fireball004.jpg " evolutionstep=0.3 /> 
<image location="fireball005.jpg " evolutionstep=0.4 /> 


</image_sequence> 


6.1.6 Text sequence 


Creating text sequences is structured the same was as creating image sequences. So, for the sequence attributes, 
there is no difference. In text_sequence, you declare text sub-sections. Obviously, specific text attributes have to 
be set in text sub sections. 


The attributes of a text sub-section are: 


value the text to be displayed 
Font Its font in a string (‘Comic Sans MS” for xample). 
size the font size 
Bold can be “true” or “false” 
italic can be “true” or “false” 
underlined can be “true” or “false” 
left, top, right and bottom | define, in pixels, a text area in the window. The text will be displayed at 
the center of this text area 
color a string containing RGB values of the text 
Example: 


<text_sequence ID="splash text’> 
<text value="text sample..” font="Arial” size=16 bold="true” italic="false” 


underlined=false” left=228 top=150 right=640 bottom=480 color="7,224,250'/> 


</text_sequence> 
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6.1.7 Full sample 


<?xml version="1.0" standalone="yes” ?> 
<splash> 
<window width=800 height=600 transparency= false” 
show="true” backgroundcolor="255, 140, 189'/> 
<progressbar x=228 y=193 width=325 height=10 backgroundcolor="255,255,255” 
showbackground="true” show="true” color="7,224,250'/> 


<step> 
<image_sequence ID="background” evol_param="time” loop="true” duration=2> 
<image location="splash.bmp” x=0 y=0 width=640 height=480 
scalex=1 scaley=1 show="true” evolutionstep=0.0 /> 
<image evolutionstep=1.0 /> 


</image_sequence> 
<image_sequence ID="foreground” evol_param="time” loop="true” duration=1,5> 


<image location="fireball001.jpg” x=100 y=0 width=800 height=600 
scalex=0.4 scaley=1 show="true” evolutionstep=0. 0 /> 

<image location="fireball005.jpg” evolutionstep=0.1 /> 

<image location="fireball010.jpg” evolutionstep=0. 2 /> 

<image location="fireball015.jpg” evolutionstep=0.3 /> 

<image location="fireball020.jpg” evolutionstep=0.4 /> 

<image location="fireball025.jpg” evolutionstep=0. 5/> 


</image_sequence> 
<text_sequence ID="splash text’> 
<text value="BITTE WARTEN SIE WAHREND TOPPS LIVE LADT... “ 

font="Arial” size=16 bold="true” italic=“false” underlined= “false” 
left=228 top=150 right=640 bottom=480 color="7,224,250'/> 

</text_sequence> 

</step> 
</splash> 


6.1.8 Some useful tips 


e When declaring a sequence, you can omit attributes that have the same value in the previous entity. 
Like in the image_sequence example given in paragraph 2.3.1. 


e You can force the redraw of an image by declaring it twice (or more) in the same sequence. It can solve 
draw issues in particular situations. 


Example: 


<image_sequence ID="background” evol_param="time” loop="true” duration=2> 
<image location="splash. jpg” x=0 y=0 width=640 height=480 
scalex=1 scaley=1 show="true” evolutionstep=0.0 /> 


<image location="splash.jpg” evolutionstep=1/> 
</image_sequence> 


Here the background image is drawn every second. 


6.1.9 Limitations 


For the time being, it is advised to: 
e not dynamically change location and scale for images in the same sequence 


e have a background image and make the other sequences (text or image) be disconnected each other 
with no common area (except with the background image) 


e not use evol_param="“progress” in steps which are not corresponding to the downloading scenario 


steps 
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e for now, it is better to use only bmp image files 


6.2 Location of downloaded files and log files 


e D’Fusion @Home Web Player: Scenario and log files 


Under Windows Vista and Windows Seven, web browsers can run under a protected mode or a non protected 
mode. Internet Explorer can be executed under a protected mode or a non protected mode. All other web 
browser (Mozilla Firefox, Safari ...) are always executed under a non protected mode. 


Windows Any Scenario SAPPDATA%S\Total Immersion\Web 
XP 
Any Logs STEMP%S\Total Immersion\WebLog 
Windows Protected Mode (IE) Scenario C:\Users\{PUT_USER_NAME_HERE} \AppData\Local\Microsoft \Windows\ 
Vietarand Temporary Internet Files\Virtualized\ 
Sane C\Users\ {PUT_USER_NAME_HERE}\AppData\Roaming\Total Immersion\Web 
Vi 
Protected Mode (IE) Logs C:\Users\{PUT_USER_NAME_HERE} \AppData\Local\Temp\Low\Total 
Immersion\WebLog 
C:\Users\{PUT_USER_NAME_HERE} \AppData\Local\Microsoft \Windows\ 
Protected Mode (IE) Sociales Temporary Internet Files\Virtualized\ 
{PUT_DOWNLOAD_PATH_HERE_REPLACING_:_BY_\} 
Non Protected Mode Scenario C:\Users\{PUT_USER_NAME_HERE} \AppData\Roaming\Total Immersion\Web 
Non Protected Mode Logs C:\Users\{PUT_USER_NAME_HERE} \AppData\Local\Temp\Total 
Immersion\WebLog 
Non Protected Mode Download (RON NDORE PATE 
MacOS Any Scenario ~/Library/Application Support/Total Immersion/Web 
English 
Any Logs ~/Library/Caches/TemporaryItems/Total Immersion/ 


e D’Fusion @Home Desktop Player: log files 


Windows XP / Vista / %TEMP%\Total Immersion\Log 


Seven 

MacOS English ~/Library/Caches/TemporaryItems/Total Immersion/Log 
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6.3 How to uninstall the D'Fusion @Home Web Plug-in on MacOS 


Erase these files manually (“Move to Trash” on English MacOS): 


/Library/Receipts/DFusionWeb.Installer.pkg 
/Library/Receipts/DFusionHomeWebPlugin.Installer.pkg 
/Library/Internet Plug-Ins/DFusionWeb.plugin 
/Library/Internet Plug-Ins/tiGeckoPluginDFusion.xpt 
/Users/username/Library/Application Support/Total Immersion 


When you try to install an older version (for example installing 2.20.1000 after having installed and uninstalled 
2.20.2000) it is possible the plug-in installation fails. The setup will say something like “a newer version of this 
package is already present on the system”. 


When this problem occurs, the only solution (at this time) is to use the pkgutil (man page) command line tools. 
e =6Use pkgutil —pkgs to list all package on the system. 
e TI packages identifiers begin with com.t-immersion. 


e Then use pkgutil -forget com.t-immersion.XXX to remove your package from the MacOSX package 
database. Note that to run this command you have to be roof. It means you have to execute this 
command using sudo (or at least su). 


6.4 How to detect if D’Fusion @Home Web Plug-ins are installed 


To detect if the D’Fusion @Home Web Plug-in needs to be installed or updated, you simply have to use the 


function tiTestDFusionPlugin() (from the file totalimmersion_dfusion_web.js). This function returns a number 
to determine the state of the plug-in: 


e 0: the plug-in is up to date. 


e 1: the plug-in needs to be installed. It means no version of the plug-in has been found on the end-user 
system). 


e 2: the plug-in need to be updated. It means the local version of the plug-in (the one currently installed 
on the end-user system) is older than the one required by the web page. 
Remarks: 


e Under Apple Mac OS X with Mozilla Firefox the plug-in version is not tested (at this time). It means only 
O or 1 can be returned. 


e Under Windows with Microsoft Internet Explorer the ActiveX version is not tested (at this time). It 
means only 0 or 1 can be returned. But not that Microsoft Internet Explorer has its own mechanism to 
install ActiveX so the end user will be automatically notified when the ActiveX need to be (re)installed. 
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6.5 How to generate Test Software Keys with tiProtectorAR2 


The tiProtectorAR2 tool is available with D’Fusion Studio Suite Pro only. You will find it in the DFusion Studio Pro 
installation folder > Deployment > Tools folder. 


You will use tiProtectorAR2 to generate a Test Software Key (and make an optional complete encrypted package) 
of a modifiable/dynamical part of your project. 


One typical use case is when you want to export and generate a Test Software Key for a folder that is to be 
downloaded from the internet, and dynamically loaded and used with your master (main) AR scenario at 
execution time depending on the final user actions. Every data used into your project has to be signed (i.e. 
associated to a Test Software Key). For downloaded data to be used correctly it has to be signed into the main 
scenario Software Key (generated when exporting your scenario) and it has to be accompanied by its own 
signature (generated with tiProtectorAR2). 


This section describes how to create a Test Software Key(s) for specific data using the tiProtectorAR2 (command 
line) tool. 


6.5.1 Using tiProtectorAR2 


To use tiProtectorAR2 for D'Fusion @Home, you must execute the following command line: 


tiProtectorAR2.exe parameters.xml [outfolder] -t @Home [-p Platform] [-e Entrypoint ] -slave | 


The following table reviews the arguments used above: 


YES parameters.xml This is the name of an XML file containing the description of the data to 
download. A sample type is provided below. 


YES out folder Folder where all the data to download is to be exported. The software key 
generated by tiProtectorAR2 will also be placed here. 


YES ~t @Home Option specifying that you're creating a Software Key for an @Home target. 


Other variables that can be used with the tiProtectorAR2 tool, as well as a sample type for “parameters.xml”, are described in 
the following section. @Home-specific use cases can be found in section “6.5.4 Use case examples”. 


6.5.2 tiProtectorAR2 arguments 


¢ parameters.xm: this is the complete path (absolute or relative) to the xml file that references all the 
data to export, and for which a Test Key is to be generated. You must create this file from scratch with a 
key-exporting compatible configuration, as shown in the example below: 
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<dfusion version="3.20.xxxxx"> 
<configurations> 
<configuration name="@Home|All Platforms" encryption="none" /> 
<configuration name="mobile|All Platforms" encryption="none" /> 
<configuration name="mobile|android" encryption="none" /> 
<configuration name="mobile|iPhoneOS" encryption="none" /> 
</configurations> 
<settings> 
<application applicationid="mobile|android:appiId; mobile|iPhoneOS:appld " title="" icon="" /> 
</settings> 
<resources> 
<files> 
<file relativePath=".\file1.mesh" /> 
<file relativePath=".\file2.scene" /> 


</files> 
</resources> 
</dfusion> 


Each tag specified in the parameters.xml file is described below: 
<configurations> <configuration> 


Attribute Description 


name String description of a “Target|Platform” configuration 
encryption String that defines the encryption process to apply when the 


configuration is exported 


<settings> <application> 


Attribute "Description 


applicationid | String that describes the application IDs for each configuration defined 
in <configurations> 


Target |Platform:applicationID; Target2|Platform2:applicationID2 


<resources> <files><file> 


Attribute “Description 


relativePath File path to the data to generate a test key for, relative to the file 
“parameters.xml” 


|" 


e outfolder: Optional (but recommended). If specified, the files that are listed in your “xml” file are 
exported into this folder, and encrypted according to the encryption specified for the selected 7arget 
and Platform (see next optional arguments). If not specified, the Test Software Key is generated in the 
folder where your “xml” file is contained, and there is no encryption. 


e -e Entrypoint: Optional. If specified, for example “-e car.scene”, the generated Software Key will be 
named “car.scene.dfk”, and the FIRST media to load from the exported folder must be the “car.scene” 
media. 


e -t Target: Optional. If not specified, the first <configuration> specified in the <configurations> list is 
used. If specified, it corresponds to the 7arget for which the export has to be done. This Target needs 
to be listed in the <configurations> tag. Possible values are: 


@Home mobile Pro 
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e -p Platform: Optional. It corresponds to the Platform for which the export has to be done. 
Dp Platfo pe ed Dp Plratfo O pe eC 

arget specified The first configuration in The first configuration in 
parameters.xml that matches parameters.xml that matches 
the specified 7arget and the specified Target is used 
Platform is used 

arget NOT specified The first configuration in The first configuration in 
parameters.xml is used parameters.xml is used 


Possible values for the Platform argument are listed below: 


| Target @Home mobile Pro 
All Platforms All Platforms All Platforms 
Platform windows android windows 
macOSX iPhoneOS macOSX 


e -slave: Mandatory for data to download dynamically. If not specified, the Software Key is marked 
“master”. If “-slave” is specified, the Software Key is marked “slave”. “Slave” indicates that the set of 
files for which the test key is to be generated are part of a bigger project, typically the files (media) to 
download dynamically from a webserver. 


\ 


Le 


The “-slave” option must be set for data to download dynamically. 


ral 


/ 


a 


A “master” scenario can ONLY use external data signed as “slave”. 


\ 


ra 


A “master” scenario can NOT use external data signed as “master”. 


ral 


/ 


a 


A D’Fusion runtime can not load a project signed as “slave”. 


6.5.3 Generated keys naming conventions 


The following points describe the naming conventions used for keys generated with the tiProtectorAR2 tool: 


v If the input xml file is a file named “myinput.xml”, the name of the output Test Software Key is 
“myinput.x7/.dfk” 


v If the input xml file is an xml file named for example “myinput.xml”, and the outfo/der option is set to 
“MyFolderToDownload', 


o If no “entry point” is defined in the “-e” argument, then the key name is “MyFo/derToDOwnload. fk", 
o If the -e “£ntrypoint" argument is specified, then the key name is “£n¢trypoint. dfk" 


Other tiProtectorAR2 arguments combinations are not recommended. 
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6.5.4 


Use case examples 


See below a sample parameters.xml file that corresponds to the following “MyFolderToDDownload” folder: 


+ MyFolderToDownload 


—- parameters.xml =) ------ > NOT to be exported 
- filel.scene = ------ > to be exported 
-— file2.mesh = — ------ > to be exported 
= f116E3.9—PG «=== > to be exported 
+ subFolderl =  — ------ > Empty folder cannot be exported 
-— file4.mesh ) ------ > to be exported 
- file5.jpg 9 =----- > to be exported 
+ subFolderl.2 = ------ > Empty folder cannot be exported 
— file6.mesh = = ------ > to be exported 
-— file7.jpg  ------ > to be exported 
+ subFolder2 = 2 = ------ > Empty folder cannot be exported 
a a > NOT to be exported 


According to the instructions above, your “parameters.xml” should contain the following code: 


fal 


<dfusion version="3.20.xxxxx"> 
<configurations> 
<configuration name="@Home|All Platforms” encryption=“encrypted” /> 
<configuration name="@Home|windows” encryption=“encrypted” /> 
<configuration name="@Home|macOSx” encryption=“encrypted” /> 
<configuration name="mobile|All Platforms” encryption=“encrypted” /> 
<configuration name=“mobile|android” encryption=“encrypted” /> 
<configuration name="mobile|iPhoneOS” encryption="encrypted” /> 
</configurations> 
<settings> 
<application applicationid="mobile|android:com.appid.testapp; mobile|iPhoneOS:com.appid.testapp “ 
title=" icon="" /> 
</settings> 
<resources> 
<files> 
<file relativePath=".\filel.scene” /> 
<file relativePath=".\file2.mesh” /> 
<file relativePath=".\file3.jpg” /> 
<file relativePath=".\subFolder1\file4.mesh” /> 
<file relativePath=".\subFolder1\file5.jpg” /> 
<file relativePath=".\subFolder1\subFolder1.2\file6.mesh” /> 
<file relativePath=".\subFolder1\subFolder1.2\file7.jpg” /> 
</files> 
</resources> 
</dfusion> 


Be carreful: The player rendering engine, Ogre3D, can use downloaded resources only from newly 
created folders. CONSEQUENTLY, A SCENARIO MUST DOWNLOAD ADDITIONAL DATA INTO A NEWLY 
CREATED FOLDER ON THE USER COMPUTER. 
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6.5.4.1 Typical use 1 (RECOMMENDED) 


When you use the tiProtectorAR2 tool to export and sign the folder to download, you can use the following 
command line: 


tiProtectorAR2.exe MyFolderToDownload\parameters.xml FinalOutName -t @Home —p windows -slave | 


The result of the previous command line execution is: 


+ FinalOutName 
— FinalOutName.dfk 
- filel.scene 
- file2.mesh 
- file3.jpg 
+ subFolderl 
- file4.mesh 
- file5.jpg 
+ subFolderl.2 
- file6é.mesh 
- file7.jpg 


6.5.4.2 Typical use 2 


When you use the tiProtectorAR2 tool to export and sign the folder to download, you can use the following 
command line: 


tiProtectorAR2.exe MyFolderToDownload\parameters.xml FinalOutName -t @Home -p windows —e 
file1.scene -slave 


The result of the previous command line execution is: 


+ FinalOutName 


- filel.scene.dfk v¥ NO CHANGE ALLOWED on the signed files. 
= ae v Key name = Media name + “.dfk” 
-— file2.mesh 
= ehies sng v First media to load = THE Media 
+ subFolderl 

~ file4.mesh No constraint on folder names, on the webserver or on the user 

~ files.jpg computer once downloaded. 

+ subFolderl1.2 

7 meee et | In our example, the first media that the scenario must load from the 


downloaded folder is “file1.scene”. 


[Be careful: The rendering engine part of the player, Ogre3D, can use downloaded resources only from 
newly created folders. CONSEQUENTLY, A SCENARIO MUST DOWNLOAD ADDITIONAL DATA INTO A 
NEWLY CREATED FOLDER ON THE USER COMPUTER. 
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6.6 License coherency using multiple Software Keys 


A Software Key can be in three different modes, depending on the tool used to generate it: 
> “Test” 
> “Test Free” 
> “Final” 

D’Fusion Studio generates a “Test Free” Software Key when exporting a project. 

D’Fusion Studio Pro and the tiProtectorAR tool generate “Test” Software Keys. 


A “Test” Software Key can be converted to “Final”. “Final” Software Keys will allow you to deploy your application 
for commercial use. 


As explained in the previous chapter of the current document, a Master key is a key that can be loaded firstly. A 
Slave key corresponds to data that can be added dynamically to the master project, and loaded in second time 
(after a download for example). 


| License coherency between Software Key modes 


Master “Test” with ... Slave “Test” = # StaveFinal 
Master “Test Free” with ... “Fest# Slave “Test Free” “Firat 
Master “Final” with ... ~ = ~ = Slave “Final” 
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7 USE CASE: WEB SOLUTION 


7.1 How to send commands from JavaScript to the player 


In the *.js files provided with the web application, you can find an “ExecuteCommand(command)" javascript 
function. This function binds directly the “command” argument to the web plug-in. This single argument have to 
be a string formatted like this: 


function_name 'argO' ‘arg1' ‘arg2’.... 


Example: 


function MakeKeystrokeActions(){ 
for (var | = 0; i < arguments.length; i++) { 
ExecuteCommand("PLAYWITHKEY "+arguments[i]+"""); 


Bs 
b 


This function can be called like this: MakeKeystrokeActions( "y", "a", ""m" ); 


For the function_name argument part there is two options: 


e It refers to a command known by the plug-in itself. So, this command is processed in the plug-in. For 
now, the available commands embed in the plug-in are: playwithkey, camselected and gofullscreen (not 
case sensitive). 


e The command is unknown from the plug-in, so it’s dispatched to the player. 


In Lite players, commands gesture is defined within the project code specific part. In each project, you have to 
edit the “ExecuteCommand” function to handle your custom commands. 


In the generic AR2 @Home player, your commands are bind to LUA such a manner that you just have to write 
some LUA script to handle. 


In your Script you have to declare a webInterface object and get commands from web plug-in: 


local webInterface = getWebInterface() 
local isCommand = 0 
local command = 0 
isCommand, command = webinterface:pullWebCommand() 
if isCommand then 
/f command{"CommandName"]=="SCALE" then 
geom:getScale(scale) 
scale:setX(command{‘argO"]) 
lf commandf{'arg1"] then 
scale:setY(command{"arg1"]) 
else 
scale:setY(command{"argO"]) 
end 
/f commandf{'arg2"] then 
scale:setZ(commandf"arg2"]) 
else 
scale:setZ(command{"argO"]) 
end 
end 
end 
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As you have noticed, the webInterface:pullWebCommand() function returns two values: a boolean (that indicates 
if an available web command have been sent from the plug-in) and a table (that contains the command name 
and all its arguments). 


7.2 How to execute JavaScript functions from a Lua script 


Here again, you need the webInterface LUA object: 


local webInterface = getWebInterface() | 


This time, this is the execJScript function that applies. 
Example: 


local text = string. format( "scaleX=%q, scaleY=%qg, 


scaleZ=%qg", scale:getX(), 


scale:getY(), scale:getZ()) 
webinterface:exeCJScript( "WriteText", text ) 


All of the parameters have to be strings. The first param is the name of the javascript functin to call. All others 
are its arguments. 
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8 TROUBLESHOOTING 


8.1 Plug-in backward compatibility 


Since D'Fusion 2.1.8814 an important bug in the plug-in is fixed. 


Before the 2.1.8814 release, if you plaid an application which required 2.1.X and you never installed any TI Web 
Player, the plug-in 2.1.X was downloaded and installed. Then, if you visited an application which required 
DFusionAR2 Web 2.1.Y, (Y < X), since release is older (Y < X), the plug-in didn't update the player as you already 


have the 2.1.X. But there was a bug in the plug-in and it was never notified that the update was finished so it 
was always waiting for it. 


With the new release everything is fixed. But to really solve the problem on applications already released, you 
have to update these applications’ Web server: only the plug-in and the JavaScript file have to be updated. 


You will find files to update in the “online\plugin” folder of the D'Fusion Web package: 


DFusionHomeWebPlugin.Installer.dmg 
DFusionHomeWebPlugin. Installer.exe 


totalimmersion_dfusion_web_plugin.js 
totalimmersion_dfusion_web_pluginMac.js 


8.2 Downloading problem 


The binary mode for download has to be ensured by the web server, this has to be configured for all files, 
even if their extension corresponds to a textual file. 


Files have to be accessible for download. 


To prevent any future problems, please ensure that this is supported and actually functional on your 
hosting web server. 


Note that these points are really important and if not ensured the D’Fusion Web application will not 
function at all, because either none files could be found on the server by the D’Fusion Web application, or, if 
found, corrupted files could be downloaded. 


8.2.1 Issues to be prevented with Apache 


e Apache on Windows: a priori, there is no problem with this configuration 


e Apache on Unix/Linux: ensure that the whole copied directory and its subdirectories have the execution 
(*X”) right set, so that the Apache server can step into. If not, the D’Fusion Web download will fail. 
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8.2.2 Issues to be prevented with IIS 


You could (and probably will) encounter problems when the hosting server is using Microsoft IIS: 


ae 


e All files that are hidden by default by Windows (those beginning with “.”), especially all occurrences of the 
“,update.xml”, need to be marked as non-hidden: just uncheck the hidden attribute. If not, the 
“,update.xml” file will not be downloadable because IIS is shielding all hidden files. 


e You'll need to ensure that all application files you’re placing onto the server (Plugin/Player/Scenario) are 
correctly registered for a binary download. That is to say, you'll need to ensure that the following MIME 
type is associated with their extension (or with all extensions via the “.*” wildcard): 


application/octet-stream 


For IIS, ensure that the MIME type for the whole project is correctly configured. To do that, click “Properties” on 
your D’Fusion Web project directory within your IIS WebSite configuration: 


= Internet Information Services 


File Action View Help 


e+ 8R|/XSAR Cm 


B Internet Information Services Name 
=) CHARLES (local computer) 
=) Web Sites 
=) @ Default Web Site 
& & IISHelp 
+) Printers 
+) 2% Default SM Explore 
Opel 
Browse 
New » 
All Tasks » 
View » 
Delete 
Rename 
Refresh 
Export List... 
Help 
< ena 


Figure 18: IIS Web site configuration 
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Then, within the “HTTP headers”, choose the “Types MIME” and configure them as shown below: 


DemoProject Properties (2 |) 


| Directory Documents Directory Security | HTTP Headers Custom Errors | ASP.NET 
{_] Enable Content Expiration 


en eee 


Content Rating 


Ratings help identify to your users what type of : ; 
content your site provides. Edit Ratings... 


MIME Map 
a To configure additional MIME types the Web 
Res 


Service sends to browsers in the HTTP 


Header, click File Types, 
g File Types 


Registered file types: 


D’Fusion® @Home 
Deployment guide 


application/octet-stream 


File type details 


Extension: 


Content Type (MIME): application“octet-stream 


Figure 19: IIS MIME types configuration 


2012-12-14 


If you do not prefer to configure whole your site via “.*” wildcard, you'll need to configure case-by-case for all file 
types present in the player’s and scenario’s directory. 


Note also, that in the Mac declination of the D’Fusion @Home Web product, there are files without extension. 


Those need to be also correctly configured for a binary download under IIS. This is done by using 


Nw 


extension. 
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The following table presents file extensions that are not defined by default in the IIS. Thus, to ensure correct 
download functionality, they need to be added manually with the corresponding MIME-type: 


.cg application/octet-stream 
.dpd application/octet-stream 
.fontdef application/octet-stream 
lua application/octet-stream 
-material application/octet-stream 
-mesh application/octet-stream 
.glsl application/octet-stream 
.mp4 video/mp4 
-nib application/octet-stream 
.0gg application/octet-stream 
.overlay application/octet-stream 
.particle application/octet-stream 
-plist application/octet-stream 
.program application/octet-stream 
«scene application/octet-stream 
.skeleton application/octet-stream 
«SSC application/octet-stream 
.strings application/octet-stream 
.tga application/octet-stream 
.xib application/octet-stream 
application/octet-stream 


8.2.3 Microsoft Visual Redist cannot be downloaded 


Sometimes, in rare use case, users failed to install the application because a firewall prevented Microsoft Visual 
redist from being downloaded. Consequently the application cannot be done correctly. 


A solution is to provide a separate link in your web page that will allow downloading the installer version that 
contains these files and correctly — installing the application. The _ installer name _ is 
“DFusionHomeWebPlugin.InstallerFull.exe” and is located in the DFusionAR2Web\online\plugin folder of the 
cdrom. Be aware that this version weights 3,4 Mo, and that downloading will take more time. 
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8.3} @Home Web player loading problem 


8.3.1 Div section must not be hidden 


e Description: the Firefox or IE plug-ins is correctly downloaded and installed, the D’Fusion @Home Web 
player is correctly downloaded but cannot be launched. 


e Solution: In the HTML page, the “div” section used for the web player must not be “hidden”, otherwise 
the player is unloaded. 


8.4 Flickering problem with Internet Explorer 


e Description 


Within an iFrame, you’re facing some flickering problem with the background of the iFrame and the video, 
while D’Fusion is running under IE (problem seems to appear most of the time only with IE6). You also 
see that the flickering disappear as soon as the scrolling bar is used or the window is resized. 


e Solution 


Write a JavaScript function to be called when the player has launched the scenario. This function will be 
executed only once (test the return value to trigger it again if failed during the next frame) as follow: 


function ActivateScenario() 


if 
7 


top.window. focus(); 


8.5 Tracking Problems 


The 3D doesn’t appear on the interactive pages that I am presenting to the camera. 


The success of the experience depends both on the lighting conditions in which you carry it out and the manner 
in which you present the pages to the camera. 


Make sure the pages are well lit, making certain that there are no shadows or reflections. 
Present the page in front of the camera, in a way that the page takes up half of the video 


Verify that your camera is not configured in mode mirror or symmetry hexagonal. 


8.5.1 I have got inverse 3D 


Sometimes there is scene inversion (tilted downwards when the panel is upwards). To rectify this, place the panel 
vertically opposite the camera and then incline it once more. 


This problem is also connected with lighting. Increase the lighting, avoid back light and this problem will be 
reduced. 


8.5.2 How to improve the lighting 


Avoid back lighting and insufficient lighting, it creates problems because the software has difficulty locating the 
tracked object. Lighting should be turned up to improve this. If you cannot improve the lighting in the room, add 
lighting to the top of the terminal. 
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8.6 Rendering Problems 


8.6.1 On some computers, materials are white instead of being textured 


It has been noticed that on one computer, all the 3D objects were blank. This computer was powerful enough for 
the project requirements. Exactly the same project did not produce this effect on another computer. 


This issue comes from the light parameters, precisely from the attenuation. In the project file (*.dpd), there was: 


attenuation="{100000, 0, 0, 0}"//"frange, constant, linear, quadratic}” | 


In the Wiki section of Ogre3D, the light attenuation formula is described as following: 


Attenuation = Constant + Linear * Distance + Quadratic * Distance*2 
Attenuation = 0 + O*distance + 0*distance*2 = 0 

And 

Luminosity = 1 / Attenuation 


There is here a division by 0! 


So it leads, on some graphic cards, to a fully blank material. 


The solution to avoid this problem is to never put the “constant” parameter at 0. 


8.6.2 On MacOSx, particles are not correctly rendered 


It has been noticed that on some mac computer, the particles are not correctly rendered. The problem comes 
from the MacOSX Ogre platform. 


Actually we have noticed 3 particle parameters causing troubles: 
e The emitter type must be set to “Point” 
e ©The affector “Scaler” must not be used with a negative scale. 


e The field “point_rendering” must be set to “false” to have the same rendering on a windows and on a 
MacOSX platform. 


A particle system file (*.particle) sample content: 


particle_system sample 


t 


point_rendering false 


emitter Point 
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8.6.3 On some Mac, textures are not correctly displayed 
It has been noticed that on some mac computer, the textures are not correctly displayed. The problem comes 
from the MacOSX Ogre platform. 
e 


Verify that the texture has a power of 2 resolution (128x128, 256x256, ...), if not: 


The material referencing it must have mipmap activated (not 0) 
e 


If it is an texture dynamically created with lua script, call setNumMipmaps() before serRessource(). 
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8.7 Recording Problems 


8.7.1 Video and Audio recording problems 


e Recorded Audio has Lag 


It has been noticed that on some computer, the Video/audio recording has some lags in the audio. The problem 
happens when using custom WMV profile (a lot of WMV profiles seem to have this problem). 


The solution to avoid this problem is to use the method: 


setVideoRecordConfig (string filePath, string type, int targetW, int targetH, float videoRate, int videoCPU, int 
videoBitRate, bool recordAudio) 


which has a default WMV profile that always works. 


e §=Captured sound always recorded. 


The difference between a file sound and a captured sound (microphone for example) is that captured sound is 
always recorded when a video is recorded even if it is not played (played by speakers). 


If you do not want to record the captured sound, then you must make it silent by using the method 
setGain(0.0) on the captured sound. The sound will still be captured (capturing microphone input), but won't be 
recorded. 
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8.8 Application crashed 


8.8.1 Graphic card does not support more than 2 lights 


Some old computers with a configuration inferior or equal to minimum hardware requirements have a graphic 
card that cannot support more than 2 virtual lights. The solution is to reduce the number of virtual lights and to 
keep only the main source lights. 
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8.9 Internet Explorer Protected Mode 


Internet Explorer (7 and >) introduced Protected Mode, a feature which helps ensure that the browser and its 
add-ons run with a minimal set of permissions. To help ensure compatibility, Protected Mode employs a system of 
virtualization so that code running within Protected Mode continue to work even if its permissions are restricted. 


However, if user switches between modes, D’Fusion Web plugin may encounter some issues. 


To be able to use the plugin under IE Protected Mode, it must be first installed under that configuration. 
Another installation may be asked for using it under Firefox or IE non Protected. Doing that way, installation 
will be proper. 


Otherwise if user first installs D’Fusion Web plugin under Firefox or IE non Protected, installation will not be 
functional for IE Protected mode and uninstallation is then requisite. 


Note. Here's how to enable/disable protected mode: 


e Open Internet Explorer. 
e From the Internet Explorer command bar, choose Tools and then Internet Options. 
e In the Internet Options window, click on the Security tab. 


e Below the Security level for this zone area, and directly above the Custom level... and Default level 
buttons, uncheck the Enable Protected Mode checkbox. 


e Note: Disabling Protected Mode requires a restart of Internet Explorer, as you may have seen next to the 
checkbox in this step. 


e Click OK on the Internet Options window. 


e If you're prompted with a Warning! dialog box, advising that The current security settings will put your 
computer at risk., click the OK button. 


e Close Internet Explorer and then open it up again. 
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